JBoss Community Archive (Read Only)

PicketLink

PicketLink Quickstarts

images/www.jboss.org/dms/picketlink/images/picketlink-banner-1180px.png

This guide will help you getting started using some examples provided by PicketLink. 

Before continue, make sure you have configured properly PicketLink in your JBoss AS 7 distribution. For more information about how to install/configure PicketLink using JBoss AS 7 see this section.

About the Quickstarts

The PicketLink Quickstarts provides some useful examples using PicketLink Federation. The examples are organized per federation protocol. PicketLink currently   supports the following:

  • Security Assertion Markup Language v2 (SAML)

  • WS-Trust

  • eXtensible Access Control Markup Language (XACML)

SAML Examples

The SAML examples helps you to understand how to configure and run a Identity Provider or Service Provider. These examples can be used for you to construct your own implementations.

The table bellow lists the Identity Providers examples provided:

Name

Description

URL

idp

Simple Identity Provider implementation

http://\[server\]:\[port\]/idp

idp-sig

Identity Provider with digital signature support for SAML assertions. All the comunication between IDP and
SPs are digitally signed

http://\[server\]:\[port\]/idp-sig

idp-enc

Identity Provider with digital signature  and encryption support for SAML assertions.

http://\[server\]:\[port\]/idp-enc\\

idp-metadata

Identity Provider using with SAML Metadata Support

http://\[server\]:\[port\]/idp-metadata\\\\

The table bellow lists the Service Providers examples provided:

Name

Description

URL

sales-post

Service Provider using HTTP POST Binding

http://\[server\]:\[port\]/sales-post\\

sales-post-sig

Service Provider using HTTP POST Binding with digital signature support for SAML assertions

http://\[server\]:\[port\]/sales-post-sig\\

sales-metadata

Service Provider using SAML Metadata Support

http://\[server\]:\[port\]/sales-metadata\\\\

employee

Service Provider using HTTP REDIRECT Binding

http://\[server\]:\[port\]/employee\\

employee-sig

Service Provider using HTTP REDIRECT Binding with digital signature support for SAML assertions

http://\[server\]:\[port\]/employee-sig\\

Which examples should I use ?

You can use any of these examples, according with your needs. If you just want to understand how PicketLink SAML Support works you should start using the examples using HTTP Redirect Binding. They can help you a lot understanding how works the communication between IDP and SPs.

These examples are very simple and helps only to demonstrate how you can configure your own implementation of Identity Providers and Service Providers.

It is important to have in mind that choosing a example with digital signature support, both IDP and SP must have this feature enabled.
Eg.: idp-sig and employee-sig/sales-post-sig.

Trust Security Token Service

Actually, the WS-Trust Security Token Service implementation is more than a quickstart is a fully compliant WS-Trust implementation using SAML tokens.

The table bellow lists the Service Providers examples provided:

Name

Description

URL

picketlink-sts

Fully compliant WS-Trust Security Token Service implementation

http://\[server\]:\[port\]/picketlink-sts/PicketLinkSTS?wsdl\\

You can use the PicketLink STS to leverage your federation to your service layer: Web Service and EJBs, for example.

XACML Policy Decision Point (PDP)

PicketLink provides a default implementation for a XACML PDP. It is responsible to evaluates and issues authorization decisions.

The table bellow lists the Service Providers examples provided:

Name

Description

URL

pdp

Fully compliant XACML Web Service

http://\[server\]:\[port\]/pdp/SOAPSAMLXACMLPDP?wsdl

How to get the Quickstarts ?

PicketLink needs to get running in different servers/containers:

  • JBoss Application Server 5

  • JBoss Application Server 7

  • Apache Tomcat 6

To achieve that the PicketLink project is organized in bindings where each binding refers to a specific target server or container.

Download from JBoss Nexus Repository

The link above allows you to download all the available distribution packages with all the examples provided. The distribution package is specific for each binding or target server.

Name

Description

picketlink-quickstarts-VERSION-webapps-jboss-as5.zip

All the examples configured for JBoss AS5

picketlink-quickstarts-VERSION-webapps-jboss-as7.zip

All the examples configured for JBoss AS7

picketlink-quickstarts-VERSION-webapps-tomcat-6.zip

All the examples configured for Apache Tomcat 6

Building the PicketLink Quickstarts Project

If you want to build the upstream version (SNAPSHOT) you need to clone and build first the PicketLink Federaton workspace. You can clone this repo from:

The quickstarts are provided as a project in github:

Follow these steps to get the quickstarts locally:

     1. Clone the project from github.

git clone git://github.com/picketlink2/picketlink-quickstarts.git

     2. Enter in the directory picketlink-quickstarts and execute a maven build:

cd picketlink-quickstarts
mvn clean install

     3. If your build was successful you should have a zip file with all examples packaged in a file called picketlink-quickstarts/target/picketlink-webapps-jboss-as7.zip.

As default, the quickstarts are configured and packaged for JBoss AS 7. For more information about how to package the quickstarts for different containers/bindings see the next section.

The master branch is our development branch. If you are looking for a specific version we recommend to checkout a specific tag.

For example, if you want the 2.1.4.Final version you can use the https://github.com/picketlink2/picketlink-quickstarts/tree/v2.1.4.Final tag.

To switch to a tag use the following git command:

git checkout v2.1.4.Final 

See the section Deploying the Quickstarts to know how to deploy the packaged applications.

Building for different containers/bindings

The quickstarts can be used in any of the available bindings/target servers, you just need to change the parameter -Dbinding and -Dbinding-version according to your needs.

The table above lists all possible combinations and supported values for both parameters:

binding

binding-version

Description

jboss

as5

mvn -Dbinding=jboss -Dbinding-version=as5 clean install, to build for JBoss AS 5

jboss

as7

mvn -Dbinding=jboss -Dbinding-version=as7 clean install, to build for JBoss AS 7

tomcat

6

mvn -Dbinding=tomcat -Dbinding-version=6 clean install, to build for Apache Tomcat 6

To build the quickstarts for one of the supported bindings use the following mvn command:

cd picketlink-quickstarts
mvn -Dbinding=jboss -Dbinding-version=as5 clean install

The command above will configure and package the quickstarts for deployment in JBoss AS 5. Use the values from the table above to change the parameters -Dbinding and -Dbinding-version.

Deploying and Running

JBoss AS v7 Configuration

Configuring the Security Domains

Before running the examples, you must add the following security-domain configurations to your standalone.xml:

<subsystem xmlns="urn:jboss:domain:security:1.0">
    <security-domains>

        ...

        <security-domain name="idp" cache-type="default">
            <authentication>
                <login-module code="UsersRoles" flag="required">
                     <module-option name="usersProperties" value="users.properties" />
                     <module-option name="rolesProperties" value="roles.properties" />
                </login-module>
            </authentication>
        </security-domain>      

        <security-domain name="picketlink-sts" cache-type="default">
            <authentication>
                 <login-module code="UsersRoles" flag="required">
                     <module-option name="usersProperties" value="users.properties" />
                     <module-option name="rolesProperties" value="roles.properties" />
                 </login-module>
             </authentication>
        </security-domain>

        <security-domain name="sp" cache-type="default">
              <authentication>
                  <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
              </authentication>
        </security-domain>

        ...

    </security-domains>
</subsystem>

These are very important configurations given that they define how both IDP, STS and SP should authenticate users. Usually you would configure your own configuration for the security domains to load users and roles from a LDAP or database, for example. The configurations above are only useful to show what do you need to configure in order to authenticate users.

You may notice that the security domain configuration for the IDP and STS references two properties files: user.properties and roles.properties. Both files are inside the WAR of the deployed IDP. These files are used to authenticate users and load the roles.

Deploying the Quickstarts

All you need to deploy the quickstarts is unzip the distribution package (generated during the build, as described before) to the [jboss.server.base.dir]/standalone/deployments.

Running the Quickstarts

To run the quickstarts start your JBoss Application Server 7 instance. Open your browser and enter the URL of the application do you want to use.

For a complete list of the URLs for each example application take a look at the table for the SAML, WS-Trust and XAML sections.

Using the Eclipse IDE

//TODO: Show how to setup a workspace using Eclipse for the quickstarts.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-11 12:17:47 UTC, last content change 2013-05-24 17:21:33 UTC.